Skip to content

feat(ContextMenu): open from a held finger on iOS 26's timeline - #8125

Draft
vjeux wants to merge 96 commits into
meta:mainfrom
vjeux:uikit/c20-contextmenu-press
Draft

vjeux wants to merge 96 commits into
meta:mainfrom
vjeux:uikit/c20-contextmenu-press

Conversation

@vjeux

@vjeux vjeux commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Stack: #11837 → #8125 → #9816 → #8133 → #8201
Merge group: #8125, #9816, #8133

Behavior module: ContextMenu's touch hold.

Supersedes #8065.

User need

A held finger should get UIKit's menu at ~0.74 s, with no click; main opens it at ~500 ms, then clicks.

Problem and solution fit

  • One touch model where the primary pointer is coarse. Under a fine pointer (spec:AST-017 FR59), or with presentation="popover", a finger keeps today's 500 ms long press.
  • The hold: the commit at 400 ms claims the finger, so its lift sends no click and the page cannot scroll. The menu shows at 735 ms or at a later lift. A drift past 11.5 px, a second finger before the commit, an early lift or a scroll opens nothing.
  • No page lock. A touch outside the open menu closes it as it pans (10 pt) or lifts.
  • A touch open lights no row.
  • The hold's moments stay internal (spec:AST-094 FR4, FR45), recorded in FR12. Its code loads after first paint; a finger that lands sooner starts the hold then. A failed load leaves today's long press, and the next touch loads again.

Current specification

spec:AST-094 FR13, FR25, FR32, FR33 and design:reduced-motion govern.

Public delta and caller burden

Default moved: under a coarse pointer, an omitted presentation means the touch model (FR25). No new export. First-load gzip: table +2,194 B, menu +1,592 B.

Design and alternatives

The shared outside-press watch replaces main's Effect (architecture:react-component-runtime INV16); a mouse press closes the menu only in its own document (family:overlay-dismissal FR8).

#11837 holds late deadlines for queued input, for every recognizer; the press keeps only its tolerance rule.

Evidence

Device takes (Android DEC-27, real-device iOS) have not run at this head (Testing).

Scope

  • One capability is added.
  • Unrelated fixes, cleanup, and policy changes were removed or split.
  • Consumer docs, focused tests, and migration evidence ship with the feature.
  • Public text and artifacts contain no internal Meta context.

Writing rubric results

Over component:ContextMenu: the pan gap goes. FR12 records the hold's moments, its before-load start, its load moment and a failed load. PR1, Ownership, the focus and FR10 gaps and the End-user row name what ships. spec:AST-094 states the 50 ms shift and the arena's one wait, and adds FR43's late begin.

Over architecture:layer-runtime: Owning code names prepare() and releasePrepared(); the outside-press list adds ContextMenu, and touch under a fine pointer or a popover.

  • R2 research: measurements stay in Testing.
  • R3 evidence: FR12's basis names the decision and measurement.
  • R1 narration, R4 rejected alternatives, R5 change references, R6 open questions, R7 project status: none.

Testing

This round, at 9cfc2fa, on main 64806d0:

  • df18912 merges main 6d00dd5. Main's perf(ContextMenu): load the touch sheet's action list only for the sheet presentation #11616 loads ContextMenu's touch sheet through DropdownMenu's lazy sheet. The merge keeps main's sheet loading and defers only the touch layer on top. The record takes main's three sheet-loading lines.

  • 7764661, red-first tests. At it, six cases fail. The gesture host pairs no pointer with a late finger, and leaves a heard but untracked finger unbegun. After a failed load, a finger gets no warning, no long press, no browser menu and no new load.

  • b919d67: the trigger keeps the touch pointerdown's id with a late finger's touchstart, and beginLateTouches pairs it. It also begins a finger the host heard but left untracked.

  • In b919d67, a failed load warns once in development, and the next touch on a trigger loads the layer again. Until then the trigger keeps no late touch. So the 500 ms long press and the browser's own menu open the menu. FR12 names the load moment: after first paint, at the next idle moment, within 2 s.

  • 104122d merges fix(gestures): a deadline runs after the input stamped before it #11837 at cf6fa67. The arena then times every recognizer's late deadline against queued input.

  • 1a404c9: the press drops its own late-move wait. Its menu shows at its moment, which the arena holds behind a block. GestureTouch.inputTime goes, with no reader left. The press's unit cases drive the arena's clock now, so they run its wait as a page does.

  • d73fbbc, records only: architecture:layer-runtime says a touch is judged at its press under presentation="popover" too.

  • 81a658c, red-first tests from aligning the load with Tooltip's (perf(Tooltip): tooltip code loads after first paint #11681). A ContextMenu in a second document waited for a frame from the page's window. A finger kept during a failed load still lost the browser's own menu.

  • fead7ee: each trigger's window schedules the load on its own frame and idle time, and the page still loads it once. Without idle callbacks, the load starts in its own task. A failed load frees a finger kept during it. FR12 takes Tooltip's FR14 wording.

  • 23afc6e merges fix(gestures): a deadline runs after the input stamped before it #11837's comment, changeset and FR16 cost line.

  • 320e8a3 merges fix(gestures): a deadline runs after the input stamped before it #11837's finger-and-pen gate. ContextMenu's touch hold is a finger's or a pen's, so the late-input wait applies to it while that contact is the latest.

  • f9c558f merges fix(gestures): a deadline runs after the input stamped before it #11837's ec2e905, which brings main 64806d0. The one conflict is spec:AST-094's verification table, which main's test(Item): the swipe's busy proof judges a held release by its curve #11735 re-aligned. The merge takes main's table and re-adds this pull request's FR43 late-begin row.

  • 9e26c1e, records only: spec:AST-094's FR16 gap note names the finger-or-pen gate.

  • db994d9, test only: the lift's click proof turns touch on from the first paint. In the touch-model case it waits for the touch layer, then presses. Before, a layer that loaded late on a busy machine failed it. With the layer's chunk held 2.5 s, the old proof fails and the new one passes.

  • fc46615, a red-first test from review: after a failed load, a trigger that mounts starts no load until a touch asks. It fails at db994d9.

  • c8446e5: after a failed load, only a touch on a trigger asks again. The failure path no longer clears the windows that scheduled the load.

  • 9f7be4c, a comment only: the pointer-order comment names no engine.

  • fbe0c1c: the shared-identity baseline allows the touch loader's four per-copy bindings, with the owners' reason (spec:AST-110 FR7).

  • add87da: the public useLayer hides prepare() by type only. A page with DropdownMenu but no ContextMenu drops 25 B.

  • 1acbd8b, a red-first test from review: after a failed load, a trigger in another document starts no load until a touch asks. It fails at add87da, where that trigger's window, which had scheduled nothing yet, scheduled a load with no intent.

  • f4076cb: once the latest load has failed, no window schedules another. Only a touch on a trigger asks again.

  • 9cfc2fa, records only: architecture:layer-runtime says useLayer's return type, not its object, leaves out the two internal members.

  • Since main's fix(gestures): each document's gesture host reads that window's clock #11155, each document's gesture host reads its own window's clock. "times a finger on the second document’s own clock: a short tap opens no menu and keeps its click" passes here.

  • First-load JS gzip over main 64806d0, on pages that import exactly these components. Those figures include fix(gestures): a deadline runs after the input stamped before it #11837, which moves these pages by 0 B.

    • docs (Text, Heading, Link, Card, Divider, List): +47 B;
    • form (Button, IconButton, TextInput, CheckboxInput, Text, Heading, Card): +103 B;
    • menu (DropdownMenu, ContextMenu, Button, Text): +1,592 B;
    • table (Table, Text, Button): +2,194 B.

    The menu page splits three ways. DropdownMenu's own default behavior through the shared menu engine adds 0 B. ContextMenu-only code that reaches a page without ContextMenu adds 172 B, measured on a DropdownMenu, Button and Text page. That code is useLayer's prepare() and outsidePress's press types, which only ContextMenu calls. The rest, about 1,420 B, is ContextMenu's own code.

    On the table page, these modules change most, in minified bytes. Layer/outsidePress +2,187, ContextMenu +1,760, contextMenuTouchLoader +1,021 (new), utils/presentation +591 (new). Then motion/uikit/gestures +364, useLayer +289 and useAdaptivePresentation −284 (gone). Table's cells import ContextMenu for their context actions, so its growth reaches every Table page. Measured as .github/scripts/lib/component-size.js measures an import: the size report's esbuild options, eager chunks only.

    Table's +2,194 B is up from +1,967 B at df18912. In minified bytes, ContextMenu grows 405 and contextMenuTouchLoader 419. They carry this round's failed-load recovery and late finger's pointer (b919d67), and the per-window load (fead7ee) with its failed-load rule (f4076cb). useLayer drops 63 (add87da).

  • This round changes the code every device run used, so earlier device runs do not carry (spec:AST-094 DEC-31).

Local checks at 9e26c1e, one worker:

  • the tests this change reaches on main 64806d0 (test:ui --changed, the boundary test included): 515 files, 15,336 passed;
  • the lazy-sheet and touch-loader boundary tests: 6 passed;
  • 34 interaction specs: ContextMenu's long press, Layer, DropdownMenu, two DateInput cases, the gesture adopters and Item's swipe. Chromium 521 passed, 31 skipped; WebKit under the CI profile 430 passed, 122 skipped;
  • 9 a11y specs in Chromium, 91 passed: ContextMenu's, Layer's press and touch trigger, the typeahead and the menu press. The cursor-anchor and Layer context-menu specs in WebKit, 7 passed;
  • the Storybook build, the core typecheck, strict eslint and prettier on the changed files, changeset coverage, check:changesets, check:knowledge, check:component-import-boundaries, and pnpm review:pre (0 findings; merges clean).

Final local checks at add87da, one worker:

  • the tests this change reaches on main 64806d0 (test:ui --changed, the boundary test included), from a fresh results cache: 515 files, 15,337 passed. Runs that reused an earlier run's order timed out three tests at the cold start. They are main's semanticFence.shared test and ContextMenu's two sheet-loading tests, from main's perf(ContextMenu): load the touch sheet's action list only for the sheet presentation #11616. On main in that order, the sheet-loading file took 27.5 s, near the 30 s limit;
  • 34 interaction specs in Chromium: 521 passed, 31 skipped. 9 a11y specs in Chromium: 91 passed;
  • the Storybook build, the core typecheck, strict eslint and prettier on the changed files, changeset coverage and check:changesets. Also check:knowledge, check:component-import-boundaries, the shared-identity check (7 passed), and pnpm review:pre (0 findings; merges clean).

The three commits after add87da add the other-document case, the loader's failed-load rule and one record sentence. At 9cfc2fa, the ContextMenu, Layer, DropdownMenu and useMenuPress units ran again: 1,361 passed. So did the core typecheck, strict eslint, prettier, check:knowledge, the shared-identity check and pnpm review:pre (0 findings; merges clean).

The previous round, at c6208ca, on main 4800d99:

  • bb998be, red-first tests. At it, the boundary test fails 3 of 3: ContextMenu's entry and Table's context-menu module reach the touch layer and the gesture host statically. The gesture host's late-begin cases fail 3 of 3. The browser case for a finger that lands before the touch layer loads fails 3 of 3 in Chromium and in WebKit. There the menu shows 736.5 ms after the landing, not 735 ms after the load.

  • 30b6b1e: ContextMenu loads its touch layer after first paint, at idle within 2,000 ms, and only while the touch model applies (contextMenuTouchLoader.ts). An input never starts the load. A finger that lands sooner keeps its touchstart on the trigger. The layer hands that touchstart to the gesture host's beginLateTouches as it mounts, so the hold starts then. Right clicks and the menu keys never wait. FR12 and spec:AST-094 FR43 gain the matching lines.

  • 779d979, red-first tests: a finger that drifts past the tolerance before the load, then comes back. At 779d979 it still gets the menu after the load. The unit cases fail on both platforms, for a touch move and for a pointer move alone. The browser case fails 3 of 3 in Chromium and in WebKit. A drift within the tolerance, and another pointer's move, keep the hold.

  • ffa0950: while the layer loads, the trigger judges the kept finger's moves by the press's own rule. It reads them from touch moves and from the primary touch pointer's moves. Past contextMenu.press.allowableMovement on either axis, it drops the touchstart, so no menu shows.

  • Before the layer loads, Chromium sends a 12.5 px drift as a pointermove only, with no touchmove. The browser case drifts 12.5 px in both engines.

  • c6208ca: comments only, in short sentences.

  • First-load JS gzip over main 4800d99, on pages that import exactly these components:

    • docs (Text, Heading, Link, Card, Divider, List): +60 B;
    • form (Button, IconButton, TextInput, CheckboxInput, Text, Heading, Card): +115 B;
    • menu (DropdownMenu, ContextMenu, Button, Text): +1,426 B;
    • table (Table, Text, Button): +2,046 B.

    At 85d7a36, menu was +22,527 B and table +23,047 B. Table's cells import ContextMenu for their context actions, so its growth reaches every Table page. Measured as .github/scripts/lib/component-size.js measures an import: the size report's esbuild options, eager chunks only.

  • The loader follows perf(core): SegmentedControl, Switch and BottomSheet load the touch animator after first paint #11450's loader contract, and it moves onto utils/touchRuntime.ts in a follow-up issue once perf(core): SegmentedControl, Switch and BottomSheet load the touch animator after first paint #11450 merges.

  • This round changes the code every device run used, so earlier device runs do not carry (spec:AST-094 DEC-31). The device runs start again at feat(ContextMenu): where a coarse pointer's held finger opens the menu (presentation unset, or adaptive where it stays a popover), the same finger slides onto an item and its lift selects it #8133's head, which contains this head.

Local checks at c6208ca, one worker:

  • the tests this change reaches on main 4800d99 (test:ui --changed, the boundary test included): 513 files, 15,298 passed;
  • lazy-sheet-bundle.test.mjs: 4 passed;
  • the long-press and keyboard-capped lists specs, every case three times: Chromium 63 passed; WebKit under the CI profile 51 passed, 12 skipped. WebKit's skips include the lift-before-load case: a scripted touch makes no click there;
  • the LayerPressTransform, BoxHold, LayerEntranceSide and LayerPanLightDismiss interaction specs and the gesture specs: Chromium 160 passed, 13 skipped; WebKit 125 passed, 48 skipped;
  • the a11y specs in Chromium (41 passed): the ContextMenu audit, long-press, cursor-anchor, menu hover-focus, Table cell-menu, ChatComposer dialog and Table resize-edge specs;
  • the cursor-anchor a11y spec in WebKit (3 passed);
  • the core typecheck, strict eslint and prettier on the changed files, changeset coverage, check:changesets, check:knowledge, and pnpm review:pre (0 findings; merges clean).

The previous round, at 85d7a36, on main 4800d99:

Local checks at 85d7a36, one worker:

  • the tests the change reaches on main 4800d99 (test:ui --changed): 512 files, 15,274 passed;
  • the long-press and keyboard-capped lists specs, every case three times: Chromium 51 passed; WebKit under the CI profile 42 passed, 9 skipped. The new Table-header case passes in both;
  • in Chromium: the ContextMenu audit, long-press a11y, cursor-anchor, menu hover-focus, ChatComposer dialog and Table resize-edge specs (35 passed); in WebKit: the cursor-anchor spec (3 passed);
  • the core typecheck, strict eslint and prettier on the changed files, changeset coverage, check:changesets and check:knowledge.

Before that, at 06b982f, on main 36f68b0:

Local checks at 06b982f, one worker:

  • the tests the change reaches on main 36f68b0 (test:ui --changed): 496 files, 14,799 passed;
  • the long-press and keyboard-capped lists specs, every case three times: Chromium 48 passed; WebKit under the CI profile 39 passed, 9 skipped;
  • the ContextMenu audit, long-press a11y, cursor-anchor and menu hover-focus specs in Chromium (31 passed), and the cursor-anchor spec in WebKit (3 passed);
  • the core typecheck, strict eslint and prettier on the changed files, changeset coverage, check:changesets and check:knowledge.

The previous round, at 8e34400, on main 56680f6:

Local checks at 8e34400, one worker:

  • the tests the change reaches on main 56680f6 (test:ui --changed): 495 files, 14,711 passed;
  • the long-press and keyboard-capped lists specs, every case three times: Chromium 48 passed; WebKit under the CI profile 39 passed, 9 skipped;
  • the ContextMenu audit, long-press a11y, cursor-anchor and menu hover-focus specs in Chromium (31 passed), and the cursor-anchor spec in WebKit (3 passed);
  • the core typecheck, strict eslint and prettier on the changed files, changeset coverage, check:changesets and check:knowledge.

The previous round, at 68be391, on main 50beab9:

  • 3632bb3, records only, from review: architecture:layer-runtime's outside-interaction list puts ContextMenu's menu on Layer's outside-press watch, which judges its press types at mousedown. The close count drops its old mousedown close.
  • 26f36d3, records only: component:ContextMenu FR10's gap names what ContextMenu owns. That is its touch model's hold, its right click and its menu keys. gestures/contextRequest.ts's plain long press does not time the hold. spec:AST-094's shared-request paragraph points to that gap.
  • 68be391, tests only, from review: the late-move case also checks that the wait stays under 70 ms. Over 30 runs the wait was 49.2 to 50.5 ms.
  • This round changes records and one test only. The product code is the same as at 5adbafb.

Local checks at 68be391, one worker:

  • check:knowledge, check:changesets, prettier on the changed files, and strict eslint on the spec;
  • the late-move case 20 times in Chromium: 20 passed;
  • the long-press and keyboard-capped lists specs, every case three times: Chromium 48 passed; WebKit under the CI profile 39 passed, 9 skipped.

The previous round, at 5adbafb, on main 50beab9:

  • d3621c0 merges main 50beab9 with no conflict. This pull request's own diff over main is unchanged (same patch-id). Main changed three files this pull request imports directly. They are hooks/useMenuPress.ts (fix(menu press): cancel only the lifted finger's touchend #11164), utils/themeProps.ts (fix(core): pass host data-* attributes to the component's own element #11406) and Layer/layerEntranceSide.ts (fix(Layer): keep a flush layer's entrance off its trigger #11417).
  • 5adbafb, tests only. The case for a slight shift just before 735 ms assumed the page got the move within 33 ms of its own time. In Chromium the page reads the timestamp the protocol hands over. A test machine took up to two frames to deliver it, so the press waited 50 ms for a late move.
  • In Chromium, the case now sends the shift at 688 ms, 25 ms ahead of its stamp. It checks that the move came on time and inside the press's wait. A new Chromium case sends the shift 60 ms after its stamp, and the menu waits 50 ms. WebKit stamps a touch as it arrives, so there the shift leaves at 688 ms. On a faster path the shift reaches the page before its stamp, which the press counts as on time.
  • Run alternately under the same load, the old case failed 11 of 20 times at fda8f0b. That earlier merge of main a4595ef is not in this pull request. At 5adbafb, the two new cases passed 20 of 20 each in Chromium, and the on-time case 10 of 10 in WebKit.

Local checks at 5adbafb, one worker:

  • the tests the change reaches on main 50beab9 (test:ui --changed): 495 files, 14,683 passed;
  • the long-press and keyboard-capped lists specs, every case three times: Chromium 48 passed; WebKit under the CI profile 39 passed, 9 skipped;
  • the ContextMenu audit, long-press a11y, cursor-anchor and menu hover-focus specs in Chromium (31 passed), and the cursor-anchor spec in WebKit (3 passed);
  • the core typecheck, strict eslint and prettier on the changed files, changeset coverage, check:changesets and check:knowledge.

The previous round, at e8d6326, on main 4d1cb82:

  • e8d6326 merges main 4d1cb82 with no conflict. This pull request's own diff over main is unchanged (same patch-id). Main changed Layer/useLayer.tsx, which this pull request also changes, and three files it imports directly. They are Layer/layerAnimations.stylex.ts and Layer/layerEntranceSide.ts (fix(Layer): keep an entrance's first frame off its trigger #11396 caps an entrance's first step by the room to its trigger) and hooks/useMenuPress.ts. Through its imports it also reaches main's motion/animator.ts.

Local checks at e8d6326, one worker:

  • the tests the change reaches on main 4d1cb82 (test:ui --changed): 493 files, 14,445 passed;
  • the long-press and keyboard-capped lists specs, every case three times: Chromium 45 passed; WebKit under the CI profile 39 passed, 6 skipped;
  • the ContextMenu audit, long-press a11y, cursor-anchor and menu hover-focus specs in Chromium (31 passed), and the cursor-anchor spec in WebKit (3 passed);
  • the core typecheck, strict eslint and prettier on the changed files, changeset coverage, check:changesets and check:knowledge.

The previous round, at 21f8156, on main 1740654:

  • dcfa0f8 merges main 1740654, which adds Core's internal useCommittedRef hook. It merges with no conflict.
  • f0b0017, red first: a transition whose render suspends never commits. When that render asks for a bottom sheet, the press must still mount the menu at the commit. At dcfa0f8 it fails: the touch layer's render-time write keeps the dropped render's commit callback, which mounts nothing.
  • e5a2bc9 removes this pull request's render-time ref writes (architecture:react-component-runtime INV17). The gesture handler calls onOpen and onCommit itself, since useGestureRecognizer keeps its newest handler in a layout Effect. onCancel goes through useCommittedRef. The outside-press watch and the menu focus are callbacks, written with useCommittedRefInto into the refs the layer's onShow reads. No committed ref is read in an Effect cleanup.
  • 3ea914d, records only: architecture:layer-runtime's outside-press line also names a touch's press, judged at its mousedown under a fine pointer (pressTypes).
  • 86f89fd and 9cccb47, comments and docs only, name only what this pull request ships. They cover the long-press spec, the motion README, the menu's style comment, the popover story, a press test's name and the timeline changeset.
  • 21f8156, records only: the End-user row states FR5's recorded gap instead of "does not yet".

Local checks at 21f8156, one worker:

  • the tests the change reaches on main 1740654 (test:ui --changed): 484 files, 14,296 passed;
  • the long-press and keyboard-capped lists specs, every case three times: Chromium 45 passed; WebKit under the CI profile 39 passed, 6 skipped;
  • the ContextMenu audit, long-press a11y, cursor-anchor and menu hover-focus specs in Chromium (31 passed), and the cursor-anchor spec in WebKit (3 passed);
  • the core typecheck, strict eslint and prettier on the changed files, changeset coverage, check:changesets and check:knowledge.

Earlier, on the iOS 26.2 Simulator at efe3f12: hold, menu, tap outside.

The previous round, at 330fcc9, on main 6ab0c2e:

  • 03eb7d7 removes the ContextMenuTouch.ts re-export; the touch layer imports contextMenuPress directly.
  • The commit-time mount stays. Without it, in WebKit under the CI profile, the menu shows 18.5 ms after the task that decides it (median of 20). Then 3 of 20 holds show it past 735 + 20 ms. With it: 2.0 ms and none, in interleaved runs. In Chromium: 6.9 and 1.8 ms.
  • f37d633, red first: a drift from before 735 ms that reaches the page behind a 250 ms block still cancels the hold (FR16). Measured first, 10 holds per arm in Chromium. With the arena's one-task yield in place of the press's 50 ms wait, the menu opened 10 of 10 times. With the press's wait, it opened 0 of 10. The case then fails 5 of 5 on the yield arm. Here it passes 5 of 5 in Chromium, where it runs.
  • 8575ec7, records only: spec:AST-094's current state names the two waits, in the spec owners' words, and the arena members the press reads; architecture:layer-runtime names pressTypes.
  • 22ae97e, records only: component:ContextMenu links motion/uikit/contextMenu.ts by path and states the moved default.
  • 7c8cb86 merges main 37f1da9; watchOutsidePress keeps both onPan and pressTypes. 650a125 merges main b8835b8, which changes only the AST-094 spec among this pull request's files.
  • 56b2f62 adds the ContextMenu iframe case: a short tap in a same-origin iframe opens no menu and keeps its click. It fails without fix(gestures): each document's gesture host reads that window's clock #11155 and passes with it.
  • fac565a, records only: Ownership names contextMenuPress.ts and ContextMenuTouchLayer.tsx.
  • 69e6dd8, comments only, from review: the touch layer's header says a second finger cancels only before the commit. The timeline's header and the long-press spec no longer name a press feedback, which this code does not have.
  • 1375867, records only, after the owners' API decision: architecture:layer-runtime's Owning code names useLayer's internal prepare() and releasePrepared(). It says what they do, and why ContextMenu mounts at the commit. The WebKit measurement stays above, in this description. The code is the same as at 69e6dd8, where the Android emulator takes run.
  • 330fcc9 merges main 6ab0c2e. Main's chore(core): remove the same-press leftovers: an unread dismissal field and stale comments #11332 removed the layer's unread wasJustDismissed and the internal types around it. The merge keeps that removal and re-adds a small internal type for prepare() and releasePrepared() only. In spec:AST-094, main's new FR6 gap and this pull request's FR16 gap sit side by side.

Local checks at 330fcc9, one worker:

  • the tests the change reaches on main 6ab0c2e (test:ui --changed): 484 files, 14,271 passed;
  • the long-press and keyboard-capped lists specs, every case three times: Chromium 45 passed; WebKit under the CI profile 39 passed, 6 skipped;
  • the ContextMenu audit, long-press a11y, cursor-anchor and menu hover-focus specs in Chromium (31 passed), and the cursor-anchor spec in WebKit (3 passed);
  • the core typecheck, strict eslint and prettier on the changed files, changeset coverage, check:changesets and check:knowledge.

Local checks at fac565a, one worker (69e6dd8 changes comments only, and 1375867 one record; the motion/uikit units pass at 69e6dd8, 314, and check:knowledge at 1375867):

  • the tests this change reaches on main b8835b8 (test:ui --changed): 481 files, 14,139 passed;
  • ContextMenuLongPress.interaction, every case five times: Chromium 40 passed; WebKit under the CI profile 30 passed, 10 skipped;
  • the gesture specs: Chromium 77 passed, 4 skipped; WebKit under the CI profile 69 passed, 12 skipped; presented hit testing 6 passed in each;
  • in Chromium, ContextMenuLongPress.a11y (3 passed), ContextMenuAudit.a11y (18 passed) and ContextMenuCursorAnchor.a11y.browser (3 passed); in WebKit, ContextMenuCursorAnchor.a11y.browser (3 passed);
  • the core typecheck, strict eslint and prettier on the changed files, changeset coverage, check:changesets and check:knowledge.

Merged main e09956b at a9188e6 ("Merge main"). git merge-tree against that main left one conflict, .changeset/outside-press-pan-watch.md. Main's v0.7.12 release (#11029) removed that changeset after shipping it, and this pull request had edited it. The merge keeps the removal and adds .changeset/contextmenu-outside-press-watch.md with this pull request's note. Otherwise this pull request's own diff is byte-identical to 20dc83f's, in the same 19 files. Main's merge changes six of this pull request's files, so the Android takes were taken again at a9188e6. Local checks on the merged tree pass: core typecheck, strict eslint on the changed files, check:changesets and check:knowledge. The ContextMenu, Layer, DropdownMenu and box-hold units pass (1,164), and so does ContextMenuLongPress in WebKit under the CI profile (3) and in Chromium (3). Its a11y spec passes too (3).

At a5a0e12, a browser case pins a finger that lifts before 400 ms as a plain tap: one click and no menu. It fails by name when the lift reaches the page at 400 ms or later. The outside-press changeset now files the change as a fix. The product code is a9188e6's. ContextMenuLongPress passes in Chromium (4, three runs) and in WebKit (3). The tap case skips in WebKit, which makes a click only from its own tap gesture.

At cae3644, a drift past 11.5 px between the commit and the menu's moment gets no menu and no click, in every engine (spec:AST-094 FR21). Red first at 3c39a05, which only lifts the case's Chromium fixme: Chromium showed the menu at 1592.8 ms. On real phones the earlier head already cancels this drift, since moves arrive in time. The fix keeps the cancel when moves reach the page late. The gesture arena holds a late input's time at its clock, so such a move looked as if it came at the menu's moment. The arena now also keeps each input's own time, as the touch's inputTime, and each coalesced sample's, as inputSamples.

The press follows the finger through each sample at its own time. A drift past 11.5 px in a sample from before the moment ends the hold, as separate moves do. At the moment, the menu waits only when the page is behind its input. A recent move from before the moment, or the moment's own timer, ran over two frames late. The wait runs on the arena's clock, and a sample from the moment on ends it with the menu. A menu timer that runs more than a frame late ran behind a blocked page. The menu then waits up to 50 ms from when the page runs again, so moves queued behind the block decide first. The press reads the page's time from the arena's injected clock, which is performance.now() in a browser. So cae3644's timing equals 45bfb44's, and the owners' real-phone still-finger check carried to it.

In a same-origin iframe or a Picture-in-Picture window, the gesture host timed touches on the page's clock, so a short tap opened the menu. Main's #11155 fixes it for every timed gesture, and 56b2f62 adds the ContextMenu case.

Red first at 3b76a8c: a finger inside 11.5 px at 735 ms that crosses it just after got no menu at a4e0404. That was 3 of 3 in Chromium, and a6253f3 showed the menu 3 of 3. Red first at 46bc0da: at 88cc0d8, a late move whose coalesced samples cross 11.5 px before the moment still showed the menu. There, a 3 px move at 700 ms that reached the page on time got the menu at 786–788 ms. That was 3 of 3 in Chromium and in WebKit. Red first at d743922: under the test harness's clock, eight press units failed at 45bfb44, which read performance.now(). Red first at 889aded: the page is blocked past the moment, until 760, 800 or 900 ms. At cad79ec, a finger that crossed 11.5 px at 650 ms still got the menu.

No other code changes: inputTime and inputSamples are read only in contextMenuPress.ts, set in GestureArena.ts, and pinned by two arena unit cases. The arena's pageTime() is read only by the press. No public entry exports GestureTouch or GestureArena; Core's internal touch entry re-exports both for Lab. pnpm api:report --check flags two reports stale from main's own changes. Regenerated, they hold no GestureTouch, inputTime or inputSamples line. ContextMenu adds no listener, window timer or clock of its own: the touch layer equals a6253f3's. The other recognizers' tests pass unchanged: the gesture units (880 in 38 files) and the core unit suite (21,504). The gesture browser specs pass in Chromium (76 passed, 4 skipped). In WebKit under the CI profile, 68 passed and 12 skipped. Presented hit testing passes 6 in each.

Measured in Chromium's phone profile, one worker, three runs each: a still finger gets the menu at 744 ms, as before. A finger creeping 6 px inside the tolerance gets it at 744–745 ms with 20 or 30 Hz moves. Those reach the page in about 25 ms. With the test driver's 60 Hz moves, which it delivers late, it gets it at 1,399–1,415 ms. Real phones' still-finger timing is the spec owners' check.

Local checks at cae3644, one worker:

  • ContextMenuLongPress.interaction: Chromium 7 passed; WebKit under the CI profile 6 passed, 1 skipped;
  • the drift, after-moment, drift-within-tolerance, 735 ms, on-time and plain-tap cases five times in Chromium (30 passed);
  • the 735 ms and on-time cases five times in WebKit (15 passed);
  • ContextMenuLongPress.a11y (3 passed), ContextMenuAudit.a11y (18 passed) and ContextMenuCursorAnchor.a11y.browser (3 passed) in Chromium;
  • ContextMenuCursorAnchor.a11y.browser in WebKit (3 passed);
  • the core typecheck, strict eslint on ContextMenu/ and gestures/, check:changesets and check:knowledge.

Main's ContextMenu opens through the same drags in Chromium. Its menu shows at 512 ms for 14–20 px drifts that cross 11.5 px before its 500 ms long press.

Replayed onto main cd748d0 after #9814's squash: 2bcc49a is one commit with this pull request's own diff at 6d7fceb. It has the same patch-id, and its message lists the folded commits. Five commits follow:

  • Red at 812d3a4: the 735 ms proof wants the show inside the timer task that decides it. A WebKit CI run had shown the menu at 758 ms, past its 20 ms.
  • Fix at 0776b40: the open commits with flushSync, under a reasoned @eslint-react/dom-no-flush-sync disable.
  • Red at e8f5ca1: the menu mounts, closed, at the commit.
  • Fix at 0fbd309: the layer hook's internal prepare() and releasePrepared() (the public useLayer does not change), and component:ContextMenu PR1 names the commit-time mount.
  • 32e75c7: the second-document test.

Then:

  • ba77ca8 merges main c8b4cba, for the harness's FrameStarvationError.
  • df6fd04: PR1 names the outside-press watch's pointer and mousedown listeners and the coarse-pointer query.
  • abb70e1: the 735 ms proof logs the page's frames (below).
  • b8a9055 merges main 62c7802, which fixes NavigationStack's busy-thread proof.
  • e66ff1d merges main 92784f6: main's fix(menus): the keys and type-ahead reach a disabled row, which stays inert #10160 dropped FR8's disabled-row gap sentence, and the FR table keeps main's FR8 text.
  • 24c03c1: the proof's starvation rule takes WebKit's catch-up frame (below).
  • 339bf7e and 3d78dae, from review: PR1 names each presentation's query subscriptions, and the record's current-state impact names the touch open's focus gap.
  • 20dc83f, a maintainer's merge of main b87846c: its tree is the merge of the two, and this pull request's own diff is unchanged.

Android exit timing (contextmenu-default): main none/64 ms, head none/72 ms (6 interleaved rounds; main max gap 101 ms)

The menu at 735 ms, page-side, with the same code one pull request up (0c316d9). The show runs inside the deciding timer task in 96 of 96 takes (0 of 96 before). It runs 1.7 ms after the decision in Chromium, 6.5 ms at 4× CPU and 3.0 ms in the WebKit CI container. Before, those were 8.8, 28.5 and 17 ms. The commit-time mount's task takes 6.8 ms at normal speed, and the growth drops no compositor frame. At 3d78dae alone, the 735 ms and commit-mount proofs pass 48 of 48 in WebKit under the CI profile and 16 of 16 in Chromium. A WebKit CI run had shown the menu at 890 ms, inside its deciding task, so that task had started late. The proof now tells why: a deciding task that starts within a frame of touch + 735 keeps the 20 ms bound. A later start fails with FrameStarvationError and its numbers under two conditions. A frame gap over 50 ms held the due time, and the task ran within two frames of the gap's end. After a long task, WebKit draws a frame and runs the delayed timer about 20 ms later. At e66ff1d, an 80 ms block failed bare there for that reason (90 ms late). Any other late start fails bare. Arms, each in both engines:

  • an 80 ms block across the due time (94a1b24) fails named, 8 of 8;
  • a 40 ms read inside the deciding task (25f99e6) fails bare on the bound, 4 of 4;
  • the menu committed 50 ms after its decision (c0bdd6f) fails bare, 4 of 4, the task having started late while frames ran.

Fine pointers (spec:AST-017 FR59, family:overlay-dismissal FR8), before and after: a ContextMenu portaled into a same-origin iframe. Before, with main's ContextMenu.tsx under 3d78dae's test (c973d19): a mouse press in the page closes the menu, and the case fails. After, at 3d78dae: a press outside the menu in its own document closes it, and one in the page does not. In the page, the mouse and pen cases pass as before.

App-level size measured at fac565a predates the deferred touch layer, so its figures no longer hold. This round's first-load figures, above, replace them.

Local checks at an earlier head, 3d78dae: check:knowledge and prettier on the record. At 24c03c1, before its two record-only commits: core typecheck and strict eslint on the spec. ContextMenuLongPress passed 3 in Chromium and 3 in WebKit under the CI profile. At e66ff1d, its parent: the ContextMenu, Layer and DropdownMenu units (1,099 passed); CI=true pnpm lint (0 errors); check:knowledge. At the stack's top on the same main, core typecheck and CI=true pnpm lint passed at all three heads (0 errors). The ui suite passed 22,774. DropdownMenuLazySheet's keyboard-open case failed once under load, and it passes alone on main and here. The node suite (test:node) passed 17,446; its one failure is the WebKit leg budget (see #8133). Earlier versions of this description said CI=true pnpm lint, but those runs were pnpm lint, which reports @eslint-react/dom-no-flush-sync only as a warning; that claim is corrected here.

The Android emulator run at an earlier head, 3d78dae: Chrome with Gboard, six takes (normal, 4× CPU and animations removed, twice each).

  • The finger-still-down menu paints 752–837 ms after landing (735 ms plus paint; the 4× takes ran under host load).
  • It opens at the finger 6 of 6.
  • An early lift and a pan open nothing 6 of 6.
  • An outside press closes it 6 of 6.

Earlier, at abb70e1, the same six takes passed every event claim. Since then, this pull request merges main twice (62c7802, 92784f6). It changes no ContextMenu source, only the 735 ms proof's starvation rule (24c03c1) and two record sentences. Earlier, at b8b8d88 (Chrome with Gboard), the finger-down menu's first frame paints 745–868 ms after the landing (735 ms plus the emulator's frames). An early lift and a pan open nothing. An outside press closes it for touch, mouse and pen.

Earlier, at 543d05f, the same own diff ran in the Chrome-with-Gboard Android emulator: six takes at normal speed, a 4× CPU slowdown and animations removed. The menu opens at the finger. An early lift and a pan open nothing. An outside press closes it for touch, mouse and pen.

Earlier, restacked on main 4598223, which has #10275's guarded presentation read, that head merged #9814's head 57f4e92. ContextMenu's usePresentation read goes through that guard, and use-table-sortable-state-hook-usage.test.tsx passes 3 of 3 here. The long-press spec's note keeps to 20 words. Local checks at 260feb3: core typecheck and that test. At the stack's top on the same base:

  • the Layer, ContextMenu, Indicator, utils, motion, gestures, DropdownMenu and hooks units (4,997 passed);
  • ContextMenuLongPress in Chromium (22 passed, 1 skipped) and in WebKit under the CI profile (19 passed, 4 skipped);
  • the three ContextMenu a11y specs (27 passed).

Earlier, restacked for the chain landing, that head merged #9814's head on main 79cc4ac. It pins boxHold.test.tsx's CheckboxList-row case to presentation="popover", since the touch model opens at 735 ms, past that case's 600 ms hold. Local checks at that head, 543d05f: core typecheck and the Layer, ContextMenu, Indicator, utils, motion and gestures units (3,550 passed). Also eslint on the changed files, check:knowledge and check:changesets.

On #9814, at the merge worker's head, which merges main 3731ec3. FR5 merges row-wise with #9915's: the row is main's, minus the pan gap this pull request closes.

The review at 279fe10, addressed:

  • The long-press a11y contract's positive control opens TouchLongPressPopover, which now ships here.
  • The Chinese usage text and the touch story name the coarse primary pointer, as the English and the changeset do.
  • One outside-press path (INV16): watchOutsidePress judges a mouse or a pen at its bubbling mousedown, as main's Effect did, so ContextMenu's own Effect goes. Red first: 5 of the 29 outsidePress.test.ts cases fail before the change; the two new guards pass either way. The shadow-root ContextMenu case now fires a mouse press's pointerdown before its mousedown, as a browser does.
  • The watch's root takes a shadow root from another window, and the constants table's header no longer claims a lazy load.
  • The FR33 notes (the finger handoff, the menu beside the lifted trigger) stay FR5's recorded gaps; feat(ContextMenu): where a coarse pointer's held finger opens the menu (presentation unset, or adaptive where it stays a popover), the same finger slides onto an item and its lift selects it #8133 hands the finger over.

Main's #9988 dismissal count: the one watch counts every outside press. Main's #9008: the record's FR8 rows and compatibility row merge row by row with this pull request's.

Local checks at c4f8964: core typecheck and the Layer, ContextMenu, DropdownMenu, utils and motion units (2,865 passed).

At #9816's head on the same base, 4efcbc4:

  • CI=true pnpm lint (0 errors), core typecheck, check:knowledge and check:changesets;
  • the ContextMenu, Layer, DropdownMenu, motion, hooks, gestures, SegmentedControl and utils units (4,809 passed);
  • the Chromium interaction specs for ContextMenu and Layer (34 passed, 1 skipped).

On the previous base (main 9e559e9), the stack's top with this content (a4a1a46, apart from two comments) passed:

  • the full ui (21,276) and node (16,672) suites;
  • the Chromium interaction specs for ContextMenu, Layer, DropdownMenu, Dialog and Drawer (60 passed, 1 skipped);
  • the same specs in WebKit (51 passed, 10 skipped);
  • their a11y contracts (330 passed).

Size figures measured on that base predate the deferred touch layer, so they no longer hold. This round's first-load figures, above, replace them.

Earlier local checks at 1af10a0, on #9814 at ed150e2 (main f10bc91):

  • core typecheck;
  • the ContextMenu, Layer, motion, hooks, gestures and DropdownMenu units with the press-coverage guard (3,408 passed);
  • strict eslint and prettier on the changed files, check:knowledge, check:changesets and the comment-length check;
  • pnpm review:pre (no findings).

Browser: ContextMenuLongPress.interaction.browser.spec.ts (the 735 ms menu, and the outside pan that closes it while the page scrolls) in Chromium and WebKit. Red first, each of these fails before the change:

  • the 735 ms menu, the lift after the commit, an early lift and a second finger;
  • a drift past the tolerance on one axis, and the claimed finger's click and scroll;
  • the outside pan and tap, and the popover and fine-pointer long press;
  • a touch open's focus, triggerAs swaps, consumer touch handlers, the commit haptic and the recognizer's states.

The timeline's other browser proofs come with #9816, held back for size. The Android emulator run at 653a5cd (Chrome; default and Remove animations) tested the unsplit touch model this stack rebuilds. It passes: the commit lands at 399–460 ms, and the menu opens at 734–746 ms at the finger. A pan gives no menu, and the menu stays open after the lift. The full gates run before this leaves draft. It changes gesture feel, so it also waits for a human check on its preview.

Test names against main: none dropped. Main's five "a menu that was never opened" tests stay exactly as main has them. Six main tests are renamed where the touch model changed what they check:

  • "opens on touch long-press" is "opens for a finger still down at 735 ms (iOS 26.2), not a millisecond before".
  • "composes consumer touch handlers with long-press detection" is now two tests. One is "passes touch events through to the consumer's own handlers". The other is "still opens at 735 ms beside a consumer onTouchStart, which runs ([Component Audit] ContextMenu: preserve nested layers and trigger events #7167)".
  • "clears a pending long-press when a consumer prevents default on touch end" is "opens nothing for an early lift whose consumer onTouchEnd prevents default ([Component Audit] ContextMenu: preserve nested layers and trigger events #7167)".
  • "cancels the long-press when the finger moves past the threshold" is now two cases. One is "cancels when the finger drifts past the tolerance on one axis (11.5 px)". The other is the popover "a drift past 10 px" case.
  • Compatibility-mousedown case: "outside the touch model, a tap outside closes the menu through its compatibility mousedown, and a scroll that starts outside leaves it open".
  • "presses that send no mousedown leave the menu open, as before" is "a mouse press that sends no mousedown leaves the menu open, as before".

Public and internal API delta

Public, changed: presentation's default under a coarse primary pointer is now the touch model (spec:AST-094 FR25). presentation="popover" keeps the released surface.
Usage: <ContextMenu presentation="popover" items={items}>{row}</ContextMenu>

Internal, new, each named in its owning record:

  • ContextMenu/contextMenuPress.ts: ContextMenuPressRecognizer times the hold's commit, display and drift (component:ContextMenu Ownership). Usage: new ContextMenuPressRecognizer().
    Why: the hold has two moments, a commit at 400 ms and a display at 735 ms. A drift rule runs until the display. Existing ones considered: main's hooks/longPressDetector.ts hold has one timer outside the gesture arena. Core's LongPressGestureRecognizer has one duration and a movement limit only until it begins. The new recognizer extends the latter. gestures/contextRequest.ts, the shared context request, holds with that plain long press. So it does not time the commit, the display or the drift rule (component:ContextMenu FR10).
  • ContextMenu/ContextMenuTouchLayer.tsx: attaches the recognizer to the Trigger area and opens the menu (Ownership). Usage: <ContextMenuTouchLayer triggerRef={triggerRef} onOpen={open} />.
    Why: the touch model's path renders only under the touch model, so the pointer path does not carry it. Existing ones considered: ContextMenu.tsx itself, which would hold both paths in one render; useGestureRecognizer, which the layer uses.
  • motion/uikit/contextMenu.ts: the hold's measured moments (component:ContextMenu, by path). Usage: contextMenu.press.commitMs // 400.
    Why: the moments need one source with their measurement notes. Existing ones considered: UIKIT_GESTURES.longPress, UIKit's long-press gesture, whose 500 ms and distance limit are a different gesture's; the file joins the existing motion/uikit domain.
  • GestureArena.pageTime(): when the page runs now, on the arena's clock (spec:AST-094 current state). Usage: this.beginTouches(event, this.arena.pageTime(), true);.
    Why: a finger begun late starts at the time the page runs, on the clock tests inject. Considered: performance.now() directly, which skips the injected clock.
  • GestureTouch.inputSamples: the positions each input came with, at their own times (spec:AST-094 current state). Usage: for (const sample of touch.inputSamples) follow(sample);.
    Why: the arena holds a late input's time at its clock and filters samples by it. So a drift sample from before the moment could be dropped. Considered: samples, which the clock filters.
  • useLayer's internal prepare() and releasePrepared(): mount a layer closed before it shows, and unmount it if it never shows (architecture:layer-runtime Owning code; component:ContextMenu PR1). The public useLayer's type does not change; its returned object also carries these two members, unnamed by the type. Usage: onCommit={layer.prepare} and onCancel={layer.releasePrepared}.
    Why: mounted at the commit, the menu shows 2.0 ms after its deciding task in WebKit. Mounted at the show, it takes 18.5 ms (Testing). Considered: the existing show path, which misses the 735 ms bound in 3 of 20 WebKit holds.
  • watchOutsidePress's pressTypes option: pointer types judged at their bubbling mousedown (architecture:layer-runtime). Usage: watchOutsidePress(owner, isInside, close, {pressTypes: ['mouse', 'pen']}).
    Why: one outside-press path for the menu (architecture:react-component-runtime INV16). Considered: main's ContextMenu mousedown Effect, the second path this replaces; pointerTypes, which picks the types the watch follows, not the moment it judges them.
  • ContextMenu/contextMenuTouchLoader.ts: useContextMenuTouchLayer(isWanted) returns the touch layer once the page has loaded it, else null, and whether its latest load failed (component:ContextMenu FR12). retryContextMenuTouchLayer() loads it again. Usage: const {layer: TouchLayer, hasFailed} = useContextMenuTouchLayer(touchModes && !isDisabled, triggerRef);.
    Why: the layer, its recognizer and the gesture host load after first paint. A page that renders a ContextMenu then does not carry them in its first load. Each trigger's window schedules the load, as Tooltip's does (perf(Tooltip): tooltip code loads after first paint #11681). After a failed load, a touch on the trigger retries (architecture:component-import-boundaries INV6). Considered: React.lazy, whose first render starts the load before paint; the shared loader in perf(core): SegmentedControl, Switch and BottomSheet load the touch animator after first paint #11450, still a draft, which a follow-up issue adopts.
  • GestureHost.beginLateTouches(touchStart, pointerId): begins, now, the fingers of a touchstart the host did not hear or left untracked, paired with the finger's pointer (spec:AST-094 FR43). Usage: getGestureHost(doc).beginLateTouches(touchStart, pointerId).
    Why: a finger that lands before the touch layer loads starts its hold once it loads (FR12), through the one press path. Its pointer lets the menu take it over (FR13). Considered: a hold timed outside the arena, a second press path; a synthetic touchstart, whose Touch objects the engines do not build alike.
  • ContextMenuTouchLayer's takeLateTouch prop: the touchstart of a finger that landed before the layer loaded and is still down, with its pointer's id. Usage: <ContextMenuTouchLayer triggerRef={triggerRef} onOpen={open} takeLateTouch={take} />.
    Why: the trigger keeps that touchstart and pointer until the layer mounts. Considered: a module-level slot, which two ContextMenus would share.

Removed earlier, never on main: the ContextMenuTouch.ts re-export.

Lines, over main 64806d0 and #11837 (ec2e905..9cfc2fa):

  • product +1,100/−95 (ContextMenu.tsx +298/−82, contextMenuPress.ts +215, contextMenuTouchLoader.ts +165, ContextMenuTouchLayer.tsx +161, motion/uikit/contextMenu.ts +90, useLayer.tsx +64/−5, GestureHost.ts +43/−5, outsidePress.ts +40/−3, GestureArena.ts +17, gestures/types.ts +7);
  • tests +3,343/−135, records +110/−65, docs +5/−5, story +69, changesets +14, shared-identity baseline +16.

Review notes

@humbertovirtudes's earlier changes-requested review was dismissed by a maintainer on Nov 12.

Follow-up after merge, from a non-blocking review note: the menu's focus after a touch open needs an indicator under forced colors. It is now a known gap in the record.

@vercel

vercel Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 15, 2026 4:41pm UTC

Request Review

@astracat-bot

astracat-bot Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟡 Reviewed (for maintainers only) Nov 15, 2026, 5:18 PM UTC

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This pull request is on hold for an engineering owner's spec decision. ContextMenu's new touch timeline (growth from 150 ms, commit at 400 ms, menu at 735 ms), the trigger growing while its menu is up, the touch scroll lock and the no-haptic choice for iOS Safari rest only on the draft ContextMenu record and the unapproved spec:AST-094. An engineering owner can record the decision by commenting /approve-spec <full head SHA> on this pull request (the author can do so as an engineering owner), or say which decision should change. Whatever that decision is, these changes are still needed:

  • Land the stacked predecessors first, or retarget onto the last of them, so that this diff is the 1,840-line ContextMenu commit rather than 24,862 authored lines.
  • Regenerate the search close CLI golden, which the new ContextMenu guidance pushes from 44 to 45 matches, so that the required test check passes.
  • Re-attach the press recognizer when the trigger node changes, because a triggerAs switch currently leaves it on the detached element (useGestureRecognizer.ts:71-79, ContextMenu.tsx:882).
  • Move the setIsTouchOpen(false) and release() calls from the Effect at ContextMenu.tsx:744-753 into the close handlers, and restore the two consumer-handler regression cases from #7167.
  • Add the ## Writing rubric results for the new AST-094 record to the description.

[Automated review]

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval is on hold until an engineering owner decides the touch direction. The ContextMenu touch timeline, the growing trigger, the touch scroll lock and the no-haptic choice for iOS Safari rest only on the draft ContextMenu record and the unapproved spec:AST-094, so an owner needs to approve or reject them and the AST-094 requirements behind them. Any engineering owner can record that decision by commenting /approve-spec <full head SHA> on this pull request, and the author can do so as an engineering owner. Whatever the decision, these fixes are still needed:

  • Land or retarget the predecessor pull requests so this one carries only the ContextMenu change (24,866 authored lines today) and lint can finish.
  • Re-attach the press recognizer when triggerAs changes, and clear the touch-opened state in the close handlers instead of an Effect.
  • Restore the two #7167 touch-handler regression cases on the new timeline, and keep a caller's touch-action from triggerXstyle.
  • Remove the gestures README section for the missing touchPresentation module, and fix AST-094's citation of the nonexistent AST-090.

[Automated review]

Comment thread packages/core/src/gestures/README.md Resolved
@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval is on hold until an engineering owner decides the ContextMenu touch direction, which rests only on the draft ContextMenu record and the unapproved spec:AST-094: the iOS timeline, the growing trigger, the touch scroll lock and no haptic in iOS Safari, the changes to the 500 ms press on other touch screens, and the AST-094 requirements behind them. Any engineering owner can record that decision by commenting /approve-spec <full head SHA> on this pull request, and the author can do so as an engineering owner. Whatever the decision, these fixes are still needed:

  • Land or retarget the predecessor pull requests so this one carries only the ContextMenu change (26,052 authored lines today).
  • Keep the released (max-width: 768px) and (pointer: coarse) query for presentation="adaptive", which the Selector record's DEC-1 says it keeps, or move the new compact query to its own pull request with a DEC-1 amendment.
  • Re-attach the press recognizer when triggerAs changes, and clear the touch-opened state in the close handlers instead of an Effect.
  • Let a caller's triggerXstyle touch-action win, and restore the two #7167 regression cases on the new timeline.
  • Fix AST-094's citation of the nonexistent AST-090, and add the ## Writing rubric results section the new record needs.

[Automated review]

@cixzhang

Copy link
Copy Markdown
Contributor

Posted by Cindy's agent on her behalf.

Parts of this PR re-implement behavior that already exists, or is being specified, as a shared part of core. Converging keeps one implementation per behavior:

This is about where the behavior lives, not about the PR's intent.

@vjeux

vjeux commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

Agreed: one implementation.

  • Writing direction: the GestureHost line belongs to the gesture host foundation, so it moves to the host's pull request, which reads isRtlElement.
  • Reduced motion: the press feedback asks the animator (animator.reducedMotion()); the local check and reducedMotion: 'keep' are gone.
  • Press feedback: the trigger becomes a pressable surface of utils/pressFeedback.ts, and its growth starts, holds and springs back on that controller's one press machine. A context-menu press profile carrying the measured onset, dated from the touch's timestamp, goes to the controller's owner; until it lands, the growth starts at the controller's own onset.
  • Long press: the hold runs on useLongPress's detector, with the measured delay and movement tolerance passed as its parameters, and useLongPress gains a second stage for the menu's moment instead of a second detector. Its 500 ms default stays for every other caller.

@vjeux
vjeux force-pushed the uikit/c20-contextmenu-press branch from d01580f to 7825a41 Compare October 25, 2026 01:37
@github-actions github-actions Bot added the needs:design-review Affects visuals — Design should review label Oct 25, 2026
@vjeux

vjeux commented Oct 25, 2026

Copy link
Copy Markdown
Contributor Author

Converged in 7825a41:

  • Press feedback: the trigger is a pressable surface of utils/pressFeedback.ts; the growth starts at the controller's "on" and springs back when its press ends. The context-menu profile (the measured onset dated from the touch, no release flash) is proposed to the controller's owner and not in yet.
  • Long press: useLongPress's detector runs the hold with the measured 400 ms delay and 11.5 px tolerance, and its new stages option opens the menu at 735 ms, so there is no second detector.
  • Reduced motion: animator.reducedMotion(); the local check and 'keep' are gone.
  • One touch model: everything keys on a coarse primary pointer (useTouchPresentation()), with no media keys in these files; the touch layer has one import site, ContextMenu/ContextMenuTouch.ts.

@vjeux

vjeux commented Oct 25, 2026

Copy link
Copy Markdown
Contributor Author

Addressed in 7825a41:

The late wait's comment in GestureArena.ts and the changeset's second
sentence each ran past 25 words. Each is now two sentences. No code
changes.
Two cases from aligning the touch layer's load with Tooltip's (meta#11681).

- A ContextMenu in a second document schedules the load on that
  document's window. Today it waits for a frame from the page's
  window, which paints none while its tab is hidden.
- A finger that lands while the load runs, which then fails, still
  gets the browser's own long-press menu. Today the trigger keeps that
  finger and cancels the browser's menu.
Aligns the touch layer's load with Tooltip's after-paint load (meta#11681).

- Each window schedules its own load, on its own frame and idle time,
  so a trigger in a frame or a Picture-in-Picture window does not wait
  on the page's window. The page still loads the layer once.
- Without idle callbacks, the load starts in its own zero-delay task.
- After a failed load, the trigger keeps no late touch, and a finger
  kept during that load gets the browser's own long-press menu.

component:ContextMenu FR12 takes Tooltip's wording for the load
moment: once per page, after the page's first paint, when the main
thread is idle and at most 2 s after that paint.
The owners asked for the late wait's cost in its own line, since it
changes when every recognizer can resolve. spec:AST-094 FR16 now says
that every recognizer's deadline whose timer runs more than 17 ms late
waits those 50 ms, even when no input is queued.
Brings the arena fix's a14908d and 88132ea: the late wait's
comment and changeset in short sentences, and spec:AST-094 FR16's line
on the wait's cost for every recognizer. No code changes.
vjeux added 17 commits November 14, 2026 23:10
From review: the late deadline's wait reads no pointer kind and can
re-arm itself.

- A mouse's late deadline keeps the one-task yield it has on main,
  with no wait. The Pager's mouse catch case returns to main's form.
- A pen's late deadline waits, as a finger's does.
- A wait whose own timer runs late, with nothing queued, runs the
  deadline instead of waiting again.
From review, and the owners' ruling on desktop timing:

- A late deadline waits for queued input only while the latest
  contact is a finger or a pen, and only their late input keeps it
  waiting. A mouse or trackpad keeps the one-task yield it has on main.
- Only the deadline's own timer counts as late. A wait whose own
  timer runs late runs the deadline, since only input from before the
  deadline extends a wait.

spec:AST-094 FR16 states the gate, and its cost line names a finger's
or pen's deadline. The changeset names the gesture arena's users only.
Brings the arena fix's 640bbfa and b7e19e3: a late deadline
waits for queued input only while the latest contact is a finger or a
pen, and a wait's own late timer does not re-arm it. ContextMenu's
touch hold is a finger's or pen's, so it keeps the wait. No conflicts.
The header's sentence on the late wait ran past 25 words. It is now
two sentences. No code changes.
From review's two non-blocking notes:

- spec:AST-094 FR16's third sentence now uses the first sentence's
  gate, "while the latest contact is a finger or a pen", as the arena
  does. It no longer names a finger's or pen's deadline.
- GestureArena.ts drops the two comments that restated
  isFingerOrPenContact and isFingerOrPen. noteArrival's comment now
  says why only a finger's or pen's late input is noted.

No code changes.
Main's meta#11735 re-aligned spec:AST-094's verification table and widened
its FR5 row. The one conflict is that table. The merge takes main's
table and re-applies this pull request's two additions to the
FR15-FR17 row: the late-deadline cases and the failure they catch.
Brings the arena fix's ec2e905: main 64806d0, FR16's third
sentence in the first sentence's gate, and two dropped comments. The
one conflict is spec:AST-094's verification table, which main's
meta#11735 re-aligned. The merge takes main's table and re-adds this pull
request's FR43 late-begin row.
spec:AST-094's FR16 gap note said a late deadline waits 50 ms or more.
Since the arena fix, that holds only while the latest contact is a
finger or a pen, as FR16 says. ContextMenu's touch hold is a finger's
or a pen's, so its menu can still show that much later.
The proof turned touch on only after the page loaded, then pressed at
once and gave the menu 2 s. The touch layer loads after the first
paint, when the page is idle, within 2 s. A finger that lands sooner
starts its hold only when the layer mounts. On a busy machine the menu
then opened after 2 s, and the proof failed.

Touch is now on from the first paint. In the touch-model case the
proof waits for the layer's chunk, its module and two frames, as the
interaction proof does, then presses. The popover story keeps today's
long press and loads no layer, so it does not wait. With the chunk
held 2.5 s, the old proof fails and the new one passes.
After a failed load, only a touch on a trigger should ask again. A
trigger that mounts is no intent, so it must start no load. This case
fails here: the failure path clears the windows that scheduled the
load, so the next trigger to mount schedules a new one.
The failure path cleared the windows that had scheduled the load, so
the next trigger to mount started a new load with no intent. The
windows now keep their mark, and only a touch on a trigger asks again,
as the touch layer's load rule says.
The comment said a finger's pointerdown follows its touchstart "as in
WebKit", with no record or probe behind it. It now names only the
order it handles.
The shared-identity check flags four module-scope bindings in the
touch loader: its state, the windows that scheduled the load, the load
in flight and the listeners. Each copy of Core loads and renders its
own touch layer, whose component reads that copy's contexts, so the
state stays per copy. The baseline allows the four with that reason.
The public hook stripped prepare() and releasePrepared() from its
return with a memo and a rest copy, on every page that uses a layer.
Only ContextMenu calls them, through useLayerInternal. The public
type already hides them, so the hook now returns the object as is.
A page with DropdownMenu but no ContextMenu drops 25 B gzip.
From review: after a failed load, a trigger whose window never
scheduled the load, such as one in a same-origin frame, still starts
one when it mounts. Only a touch should ask again, in every window.
This case mounts such a trigger after the failure; it fails here.
After a page-wide failure, a trigger whose window had not scheduled
the load still scheduled one as it mounted, with no intent. The load
now waits for a touch in every window: scheduleLoad does nothing once
the latest load has failed.
From review: since add87da the public useLayer returns the
implementation's object, so it carries prepare() and releasePrepared()
at runtime. Only its return type leaves them out. The layer-runtime
record now says so.
@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec 9cfc2fa

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested.

ContextMenu's held-finger timeline, its after-paint loading and the failed-load fallback match the touch-presentation and import-boundaries records, and an engineering owner approved this head's record text; what blocks is the device evidence for this head.

Blocking:

  • State in the description the Android emulator takes for this head (Chrome with Gboard at normal animation scale, with animations removed and in a slow-device profile), each with its result: this head changes ContextMenu.tsx, the touch loader and the gesture arena, so no earlier take carries.
  • State in the description the real-device iOS side-by-side against the head the spec owner passed, for this head or one that contains it, with its result.

@humbertovirtudes's changes-requested review also stands until they re-review or dismiss it, and CI has not run on this draft head. Non-blocking notes (a wording point in the ContextMenu record's FR12, the first-load figures as pnpm size:pages measures them, and three small cleanups) are in the review.

Claims and files checked

Review mode: same-head; reason: none

Claims:

  • Outside-press release note: a mouse or pen press closes the menu at its press in the menu's own document, so a menu in an iframe or Picture-in-Picture window no longer closes on a press in the page — verified (Layer/outsidePress.ts judges on the trigger's document; the second-document cases).
  • Timeline release note: the touch model applies where the primary pointer is coarse — verified (ContextMenu.tsx resolves an omitted presentation to the touch model).
  • At 400 ms the press takes the finger, its lift sends no click and the page cannot scroll — verified (contextMenuPress.ts commit; press unit cases).
  • The menu opens at 735 ms, or at a lift after 400 ms — verified (unit cases; a 450 ms hold as a Pixel 7 opens the menu at the lift).
  • A lift before 400 ms, or a drift past 11.5 px before the menu, opens nothing — verified (unit cases).
  • The page scrolls while the menu is up, and a touch outside closes it as it pans or lifts — verified (outside cases and the watch's pan cases).
  • A touch open lights no row; keyboard and pointer opens focus the first item — verified (focus cases; captures).
  • A second finger cancels only before 400 ms — verified (press unit cases).
  • A fine pointer keeps the right-click menu and the 500 ms long press, and the popover presentation keeps today's menu — verified (popover and fine-pointer cases).
  • The touch code loads after the first paint, and a finger held before then starts its hold once it loads — verified (boundary test; before-load cases).
  • Arena release note: a late finger or pen deadline waits for queued input, a mouse's does not, a deadline among a coalesced move's samples runs between them, and a long-press hold or a Pager catch whose finger drifted in time now ends — verified (arenaTimersAndClaims.test.ts with a long-press recognizer; Pager cases).
  • Description, the default moves under a coarse pointer and no export is added — verified (API surface comparison: one changed default).
  • Description, first-load gzip figures on the four reference pages — measured with another tool; pnpm size:pages at this head gives docs +83 B, form +61 B, menu +1,844 B, table +2,237 B (non-blocking note).
  • Description, the shared outside-press watch replaces the component's own listener — verified (the Effect is gone).
  • Description, the arena holds late deadlines for every recognizer and the press keeps only its tolerance rule — verified (GestureArena.ts, contextMenuPress.ts).
  • Description, a failed load warns once and the next touch loads the layer again, while the long press and the browser's own menu open the menu — verified (failed-load test file); a browser may keep a failed module import, so the next touch asks again (non-blocking wording note).
  • Description, a late finger keeps its pointer and a heard but untracked finger begins — verified (gesture host late-begin cases).
  • Description, each trigger's window schedules the load, and after a failed load no window schedules another — verified (loader; failed-load cases in a second document).
  • Description, the public useLayer hides the internal members by type only — verified (useLayer.tsx).
  • Description, device takes have not run at this head — true (blocking above).
  • Description, local checks — rerun at this head: the touched unit suites pass (1,493 tests), strict lint is clean, and the Core build's typecheck passes.
  • Description, the stack line — the declared stack does not hold at the current heads, so this pull request is reviewed alone.

Files:

  • .changeset/contextmenu-outside-press-watch.md, .changeset/contextmenu-touch-timeline.md, .changeset/gesture-arena-late-input.md — clear.
  • apps/storybook/stories/ContextMenu.stories.tsx — clear.
  • docs/architecture/layer-runtime.md — clear.
  • docs/specs/AST-094-touch-presentations/spec.md — clear.
  • docs/specs/components/ContextMenu/ContextMenu.spec.md — non-blocking wording note (FR12 "loads it again").
  • packages/core/src/ContextMenu/ContextMenu.doc.mjs — clear.
  • packages/core/src/ContextMenu/ContextMenu.test.tsx, ContextMenu.touchLoadFailure.test.tsx — clear.
  • packages/core/src/ContextMenu/ContextMenu.tsx — clear.
  • packages/core/src/ContextMenu/ContextMenuTouchLayer.tsx — clear.
  • packages/core/src/ContextMenu/__tests__/ContextMenuLongPress.a11y.chromium.spec.ts — clear.
  • packages/core/src/ContextMenu/__tests__/ContextMenuLongPress.interaction.browser.spec.ts — non-blocking note (header).
  • packages/core/src/ContextMenu/contextMenuPress.ts — non-blocking note (clockTime).
  • packages/core/src/ContextMenu/contextMenuPress.test.ts — clear.
  • packages/core/src/ContextMenu/contextMenuTouchLoader.ts, contextMenuTouchLoader.boundary.test.ts — clear.
  • packages/core/src/Indicator/boxHold.test.tsx — clear.
  • packages/core/src/Layer/outsidePress.ts — non-blocking note (behavior outside the scope).
  • packages/core/src/Layer/outsidePress.test.ts, packages/core/src/Layer/useLayer.tsx, packages/core/src/Layer/useLayer.test.tsx — clear.
  • packages/core/src/gestures/GestureArena.ts — non-blocking note (constants between imports).
  • packages/core/src/gestures/GestureHost.ts, packages/core/src/gestures/types.ts — clear.
  • packages/core/src/gestures/__tests__/GestureHost.test.ts, arena.test.ts, arenaTimersAndClaims.test.ts, harness.ts — clear.
  • packages/core/src/hooks/usePager.test.ts — clear.
  • packages/core/src/motion/README.md, packages/core/src/motion/uikit/contextMenu.ts — clear.
  • scripts/shared-identity.baseline.json — clear.

Automated review (maintainer link)

| FR9 | While the Pointer menu surface is open, it participates in `family:overlay-dismissal` through the shared stack and provides descendant depth. One Escape press affects only the top-most present nested surface; ContextMenu closes only when it is that surface. | `family:overlay-dismissal` FR1–FR6; `ContextMenu.test.tsx` nested-layer case |
| FR10 | ContextMenu MUST be built on the public headless context menu (`spec:AST-107` FR8), with its invocation, open state, and cleanup the factory's and no behavior of its own beside the factory's. Implementation gap: no headless context menu ships. ContextMenu owns its invocation: its touch model's hold (the 400 ms commit, the 735 ms display and the drift rule, which `gestures/contextRequest.ts`'s plain long press does not time), its right click and its menu keys. It owns its open state and cleanup, and closes on an outside press through Layer's outside-press watch. | `spec:AST-107` FR8 |
| FR11 | Tab or Shift+Tab on a row of the pointer menu, its own or an open sub-menu flyout's at any depth, closes every open level and the menu and calls `onOpenChange(false)` once, as `component:DropdownMenu` FR23 states for its menu. | WAI-ARIA Menu Button pattern; current tests |
| FR12 | Under a finger, the hold commits at 400 ms and the menu displays at 735 ms, as UIKit's do. They are measured input, not motion, and stay internal (`spec:AST-094` FR4, FR45). A finger that lands before the touch layer has loaded starts the hold once it loads; a mouse or keyboard opens as today. The touch layer loads once per page, after the page's first paint, when the main thread is idle and at most 2 s after that paint. No input starts or hurries the load. If it fails to load, a finger gets today's 500 ms long press, and the next touch loads it again. | Measured: UIContextMenuInteraction on the iOS 26.2 simulator commits at 400 ms and displays its menu at 735 ms (`motion/uikit/contextMenu.ts`); `spec:AST-094` FR4, FR45 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: "the next touch loads it again" says more than the code can promise. utils/moduleLoader.ts:16-20 notes that a browser does not fetch a native module again once its import failed, so a touch asks the loader again, as architecture:component-import-boundaries INV6 words it. Suggest: "If it fails to load, a finger gets today's 500 ms long press, and the next touch asks for it again."

* A deadline's timer counts as late when it runs this long after it was due.
* In ms: one frame at 60 Hz.
*/
const LATE_TIMER_MS = 17;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: these three constants sit between two import statements (import {internals} from './recognizerInternals'; follows at line 83). Move them below the imports.

* @output Interaction and animation proofs for a context menu that a held
* finger opens on UIKit's timeline. They cover the menu's moments, on
* time and behind a blocked main thread. They also cover the page under
* the finger, a pan outside and a storyboard of the press

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: the file has no storyboard case, so "and a storyboard of the press" can go: "They also cover the page under the finger and a pan outside."

This branch was successfully deployed

1 active deployment
Preview — 9cfc2fab Deployed Nov 15, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:run A maintainer lets this outside contributor's pull request run CI (AST-030 FR17) ci:run-a11y Run the accessibility suite on this PR; write access, next push (AST-030 FR12) CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants